/*
 * Copyright (c) 2001, 2003, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package com.sun.corba.se.impl.oa.poa;

import org.omg.PortableServer.Servant;
import org.omg.PortableServer.ServantManager;
import org.omg.PortableServer.ForwardRequest;

import org.omg.PortableServer.POAPackage.ObjectAlreadyActive;
import org.omg.PortableServer.POAPackage.ServantAlreadyActive;
import org.omg.PortableServer.POAPackage.ServantNotActive;
import org.omg.PortableServer.POAPackage.NoServant;
import org.omg.PortableServer.POAPackage.WrongPolicy;
import org.omg.PortableServer.POAPackage.ObjectNotActive;

/**
 * POAPolicyMediator defines an interface to which the POA delegates all
 * policy specific operations.  This permits code paths for different
 * policies to be optimized by creating the correct code at POA creation
 * time.  Also note that as much as possible, this interface does not
 * do any concurrency control, except as noted.  The POA is responsible
 * for concurrency control.
 */
public interface POAPolicyMediator {
    /**
     * Return the policies object that was used to create this
     * POAPolicyMediator.
     */
    Policies getPolicies();

    /**
     * Return the subcontract ID to use in the IIOP profile in IORs
     * created by this POAPolicyMediator's POA.  This is initialized
     * according to the policies and the POA used to construct this
     * POAPolicyMediator in the POAPolicyMediatorFactory.
     */
    int getScid();

    /**
     * Return the server ID to use in the IIOP profile in IORs
     * created by this POAPolicyMediator's POA.  This is initialized
     * according to the policies and the POA used to construct this
     * POAPolicyMediator in the POAPolicyMediatorFactory.
     */
    int getServerId();

    /**
     * Get the servant to use for an invocation with the
     * given id and operation.
     *
     * @param id        the object ID for which we are requesting a servant
     * @param operation the name of the operation to be performed on
     *                  the servant
     * @return the resulting Servant.
     */
    java.lang.Object getInvocationServant(byte[] id,
                                          String operation) throws ForwardRequest;

    /**
     * Release a servant that was obtained from getInvocationServant.
     */
    void returnServant();

    /**
     * Etherealize all servants associated with this POAPolicyMediator.
     * Does nothing if the retention policy is non-retain.
     */
    void etherealizeAll();

    /**
     * Delete everything in the active object map.
     */
    void clearAOM();

    /**
     * Return the servant manager.  Will throw WrongPolicy
     * if the request processing policy is not USE_SERVANT_MANAGER.
     */
    ServantManager getServantManager() throws WrongPolicy;

    /**
     * Set the servant manager.  Will throw WrongPolicy
     * if the request processing policy is not USE_SERVANT_MANAGER.
     */
    void setServantManager(ServantManager servantManager) throws WrongPolicy;

    /**
     * Return the default servant.   Will throw WrongPolicy
     * if the request processing policy is not USE_DEFAULT_SERVANT.
     */
    Servant getDefaultServant() throws NoServant, WrongPolicy;

    /**
     * Set the default servant.   Will throw WrongPolicy
     * if the request processing policy is not USE_DEFAULT_SERVANT.
     */
    void setDefaultServant(Servant servant) throws WrongPolicy;

    void activateObject(byte[] id, Servant servant)
            throws ObjectAlreadyActive, ServantAlreadyActive, WrongPolicy;

    /**
     * Deactivate the object that is associated with the given id.
     * Returns the servant for id.
     */
    Servant deactivateObject(byte[] id) throws ObjectNotActive, WrongPolicy;

    /**
     * Allocate a new, unique system ID.  Requires the ID assignment policy
     * to be SYSTEM.
     */
    byte[] newSystemId() throws WrongPolicy;

    byte[] servantToId(Servant servant) throws ServantNotActive, WrongPolicy;

    Servant idToServant(byte[] id) throws ObjectNotActive, WrongPolicy;
}
